In This Topic

The dataset metadata describes the content and semantics of a dataset in OPC UA PubSub. In QuickOPC, it is represented by an instance of the UADataSetMetaData Class. When you are subscribing to a dataset, metadata is an optional part of the dataset subscription descriptor (UADataSetSubscriptionDescriptor Class), in its DataSetMetaData Property.

The main part of the dataset metadata are field definitions - a metadata for each of the fields contained in the dataset. This is a collection of UAFieldMetaData Class instances, contained in the collection stored in the Fields Property. Each field metadata contains following data members:

Name Property. The name of the field.
Description Property. Description of the field.
DataSetFieldId Property. The unique ID for the field in the dataset, expressed as a string.
BuiltInType Property. The built-in data type of the field.
DataTypeId Property. The node Id of the data type of this field.
MaximumStringLength Property. Specifies the maximum supported length of a String or ByteString.
ValueRank Property. Indicates whether the data type is an array and how many dimensions the array has.
ArrayDimensions Property. Specifies the maximum supported length of each dimension.
DataSetFieldFlags Property. Flags for the field.

Most of the data members have reasonable defaults, and some are not necessary at all times. The Description Property, the DataSetFieldId Property and the DataSetFieldFlags Property are optional. In the most typical case of scalar fields of built-in types, you can leave the DataTypeId Property, the MaximumStringLength Property and the ValueRank Property at their defaults.

Besides the field metadata, the dataset metadata contains some data members that apply to the dataset as a whole. They are:

Name Property. Name of the dataset.
Description Property. Description of the dataset.
ConfigurationVersion Property. The configuration version for the current configuration of the dataset.
DataSetClassId Property. Provides the globally unique identifier of the class of dataset if the dataset is based on a dataset class.

Do I need the metadata?

The answer is: It depends. Some message mappings (such as JSON) as largely self-descriptive, meaning that even without the metadata, it is possible to decode the dataset messages and event obtain metadata-like information, such as field names, from the dataset message itself. Other message mappings (such as UADP) are more compact, and not fully (or not at all) self-descriptive. The UADP message mapping does not transfer field names in the messages. Consequently, without metadata, QuickOPC will deliver to you the datasets with field indexes (such as "#0", "#1", ...) instead of field names - but in general, things will work. If you use the UADP message mapping and the dataset is encoded with the RawData encoding (check with the publisher), you must have metadata in order to be able to decode the dataset messages.

Where do I get the metadata from?

There are several (or rather, many) ways of obtaining the metadata, and applying them. Below are some of them.

With OPC UA PubSub logical resolution, you let QuickOPC get the metadata from PubSub configuration residing in a standard OPC UA server, or a PubSub configuration file. No additional coding is needed.
You may access the PubSub configuration from your code, and then retrieve the published dataset element by calling the FindPublishedDataSetElement Method or the GetPublishedDataSetElement Method, and get the dataset metadata from the DataSetMetaData Property of the UAPublishedDataSetElement Class instance.
You obtain the metadata information in other form (maybe somebody described it in the document, or you read it in your program from some other file format), and you will write code that constructs the instance of the UADataSetMetaData Class. This is described in more details further below.

Defining metadata in code

In order to define the metadata in your code, create an instance of the UADataSetMetaData Class, and fill in its properties and the Fields collection as necessary. Then, assign this dataset metadata instance to the DataSetMetaData Property of the UADataSetSubscriptionDescriptor Class instance that you will use to make your dataset subscription. There are also some extension method overloads of the SubscribeDataSet Method that take the dataset metadata directly as one of their arguments.

In languages like C# or VB.NET, you can take advantage of the fact that the UADataSetMetaData Class support collection initializer syntax for its field, making the code even shorter. This approach is also shown in the example below.

.NET

// This example shows how to subscribe to dataset messages with RawData field encoding, specifying the metadata necessary
// for their decoding directly in the code.
//
// In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see
// https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .

using System;
using System.Collections.Generic;
using System.Threading;
using OpcLabs.EasyOpc.UA;
using OpcLabs.EasyOpc.UA.PubSub;
using OpcLabs.EasyOpc.UA.PubSub.Configuration;
using OpcLabs.EasyOpc.UA.PubSub.OperationModel;

namespace UADocExamples.PubSub._EasyUASubscriber
{
    partial class SubscribeDataSet
    {
        public static void Metadata()
        {
            // Define the PubSub connection we will work with. Uses implicit conversion from a string.
            UAPubSubConnectionDescriptor pubSubConnectionDescriptor = "opc.udp://239.0.0.1";
            // In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to
            // the statement below. Your actual interface name may differ, of course.
            //pubSubConnectionDescriptor.ResourceAddress.InterfaceName = "Ethernet";

            // Define the filter. Publisher Id (unsigned 16-bits) is 30, and the writer group Id is 101.
            // The dataset writer Id (1) must not be specified in the filter, because it does not appear in the message.
            var filter = new UASubscribeDataSetFilter(UAPublisherId.CreateUInt16(30), writerGroupDescriptor: 101);

            // Define the metadata, with the use of collection initializer for its fields.
            var metaData = new UADataSetMetaData
            {
                new UAFieldMetaData("BoolToggle", UABuiltInType.Boolean),
                new UAFieldMetaData("Int32", UABuiltInType.Int32),
                new UAFieldMetaData("Int32Fast", UABuiltInType.Int32),
                new UAFieldMetaData("DateTime", UABuiltInType.DateTime)
            };

            // Define the dataset subscription, with specific communication parameters.
            // The dataset offset is needed with messages that do not contain dataset writer Ids and use RawData field
            // encoding. An exception to this rule is when the dataset is the only or first in the dataset message payload,
            // which is also the case here, but we are specifying the dataset offset anyway, for illustration.
            var dataSetSubscriptionDescriptor = new UADataSetSubscriptionDescriptor(
                pubSubConnectionDescriptor, filter, metaData)
            {
                CommunicationParameters = { UadpDataSetReaderMessageParameters = { DataSetOffset = 15 }}
            };

            // Instantiate the subscriber object and hook events.
            var subscriber = new EasyUASubscriber();
            subscriber.DataSetMessage += subscriber_DataSetMessage_Metadata;

            Console.WriteLine("Subscribing...");
            subscriber.SubscribeDataSet(dataSetSubscriptionDescriptor);

            Console.WriteLine("Processing dataset message events for 20 seconds...");
            Thread.Sleep(20 * 1000);

            Console.WriteLine("Unsubscribing...");
            subscriber.UnsubscribeAllDataSets();

            Console.WriteLine("Waiting for 1 second...");
            // Unsubscribe operation is asynchronous, messages may still come for a short while.
            Thread.Sleep(1 * 1000);

            Console.WriteLine("Finished.");
        }

        static void subscriber_DataSetMessage_Metadata(object sender, EasyUADataSetMessageEventArgs e)
        {
            // Display the dataset.
            if (e.Succeeded)
            {
                // An event with null DataSetData just indicates a successful connection.
                if (!(e.DataSetData is null))
                {
                    Console.WriteLine();
                    Console.WriteLine($"Dataset data: {e.DataSetData}");
                    foreach (KeyValuePair<string, UADataSetFieldData> pair in e.DataSetData.FieldDataDictionary)
                        Console.WriteLine(pair);
                }
            }
            else
            {
                Console.WriteLine();
                Console.WriteLine($"*** Failure: {e.ErrorMessageBrief}");
            }
        }

        // Example output:
        //
        //Subscribing...
        //Processing dataset message events for 20 seconds...
        //
        //Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
        //[BoolToggle, False {System.Boolean}; Good]
        //[Int32, 3072 {System.Int32}; Good]
        //[Int32Fast, 894 {System.Int32}; Good]
        //[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good]
        //
        //Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
        //[BoolToggle, False {System.Boolean}; Good]
        //[Int32, 3072 {System.Int32}; Good]
        //[Int32Fast, 920 {System.Int32}; Good]
        //[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good]
        //
        //Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
        //[BoolToggle, False {System.Boolean}; Good]
        //[Int32, 3073 {System.Int32}; Good]
        //[Int32Fast, 1003 {System.Int32}; Good]
        //[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good]
        //
        //Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
        //[BoolToggle, False {System.Boolean}; Good]
        //[Int32, 3073 {System.Int32}; Good]
        //[Int32Fast, 1074 {System.Int32}; Good]
        //[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good]
        //
        //Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
        //[BoolToggle, True {System.Boolean}; Good]
        //[Int32, 3074 {System.Int32}; Good]
        //[Int32Fast, 1140 {System.Int32}; Good]
        //[DateTime, 10/1/2019 12:21:16 PM {System.DateTime}; Good]
        //
        //...
    }
}

# This example shows how to subscribe to dataset messages with RawData field encoding, specifying the metadata necessary
# for their decoding directly in the code.
#
# In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see
# https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used.
#
# Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
# OPC client and subscriber examples in Python on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-Python .
# The QuickOPC package is needed. Install it using "pip install opclabs_quickopc".
import opclabs_quickopc
import time

# Import .NET namespaces.
from OpcLabs.EasyOpc.UA import *
from OpcLabs.EasyOpc.UA.PubSub import *
from OpcLabs.EasyOpc.UA.PubSub.Configuration import *
from OpcLabs.EasyOpc.UA.PubSub.OperationModel import *


def dataSetMessage(sender, e):
    # Display the dataset.
    if e.Succeeded:
        # An event with null DataSetData just indicates a successful connection.
        if e.DataSetData is not None:
            print('')
            print('Dataset data: ', e.DataSetData, sep='')
            for pair in e.DataSetData.FieldDataDictionary:
                print(pair)
    else:
        print('')
        print('*** Failure: ', e.ErrorMessageBrief, sep='')


# Define the PubSub connection we will work with. Uses implicit conversion from a string.
pubSubConnectionDescriptor = UAPubSubConnectionDescriptor.op_Implicit('opc.udp://239.0.0.1')
# In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to
# the statement below. Your actual interface name may differ, of course.
#pubSubConnectionDescriptor.ResourceAddress.InterfaceName = 'Ethernet'

# Define the filter. Publisher Id (unsigned 16-bits) is 30, and the writer group Id is 101.
# The dataset writer Id (1) must not be specified in the filter, because it does not appear in the message.
filter = UASubscribeDataSetFilter(UAPublisherId.CreateUInt16(30),
                                  UAWriterGroupDescriptor(101))

# Define the metadata.
metaData = UADataSetMetaData()
metaData.Add(UAFieldMetaData('BoolToggle', UABuiltInType.Boolean))
metaData.Add(UAFieldMetaData('Int32', UABuiltInType.Int32))
metaData.Add(UAFieldMetaData('Int32Fast', UABuiltInType.Int32))
metaData.Add(UAFieldMetaData('DateTime', UABuiltInType.DateTime))

# Define the dataset subscription, with specific communication parameters.
# The dataset offset is needed with messages that do not contain dataset writer Ids and use RawData field
# encoding. An exception to this rule is when the dataset is the only or first in the dataset message payload,
# which is also the case here, but we are specifying the dataset offset anyway, for illustration.
dataSetSubscriptionDescriptor = UADataSetSubscriptionDescriptor(pubSubConnectionDescriptor, filter, metaData)
dataSetSubscriptionDescriptor.CommunicationParameters.UadpDataSetReaderMessageParameters.DataSetOffset = 15

# Instantiate the subscriber object and hook events.
subscriber = EasyUASubscriber()
subscriber.DataSetMessage += dataSetMessage

print('Subscribing...')
subscriber.SubscribeDataSet(EasyUASubscribeDataSetArguments(dataSetSubscriptionDescriptor))

print('Processing dataset message events for 20 seconds...')
time.sleep(20)

print('Unsubscribing...')
subscriber.UnsubscribeAllDataSets()

print('Waiting for 1 second...')
# Unsubscribe operation is asynchronous, messages may still come for a short while.
time.sleep(1)

subscriber.DataSetMessage -= dataSetMessage

print('Finished.')

' This example shows how to subscribe to dataset messages with RawData field encoding, specifying the metadata necessary
' for their decoding directly in the code.
'
' In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see
' https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .

Imports OpcLabs.EasyOpc.UA
Imports OpcLabs.EasyOpc.UA.PubSub
Imports OpcLabs.EasyOpc.UA.PubSub.Configuration
Imports OpcLabs.EasyOpc.UA.PubSub.OperationModel

Namespace PubSub._EasyUASubscriber
    Partial Friend Class SubscribeDataSet
        Public Shared Sub Metadata()

            ' Define the PubSub connection we will work with. Uses implicit conversion from a string.
            Dim pubSubConnectionDescriptor As UAPubSubConnectionDescriptor = "opc.udp://239.0.0.1"
            ' In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to
            ' the statement below. Your actual interface name may differ, of course.
            ' pubSubConnectionDescriptor.ResourceAddress.InterfaceName = "Ethernet"

            ' Define the filter. Publisher Id (unsigned 16-bits) is 30, and the writer group Id is 101.
            ' The dataset writer Id (1) must not be specified in the filter, because it does not appear in the message.
            Dim filter = New UASubscribeDataSetFilter(UAPublisherId.CreateUInt16(30))
            filter.WriterGroupDescriptor.WriterGroupId = 101

            ' Define the metadata, with the use of collection initializer for its fields.
            Dim metaData = New UADataSetMetaData From {
                New UAFieldMetaData("BoolToggle", UABuiltInType.Boolean),
                New UAFieldMetaData("Int32", UABuiltInType.Int32),
                New UAFieldMetaData("Int32Fast", UABuiltInType.Int32),
                New UAFieldMetaData("DateTime", UABuiltInType.DateTime)
            }

            ' Define the dataset subscription, with specific communication parameters.
            ' The dataset offset is needed with messages that do not contain dataset writer Ids and use RawData field
            ' encoding. An exception to this rule is when the dataset is the only or first in the dataset message payload,
            ' which is also the case here, but we are specifying the dataset offset anyway, for illustration.
            Dim dataSetSubscriptionDescriptor = New UADataSetSubscriptionDescriptor(
                pubSubConnectionDescriptor, filter, metaData)
            dataSetSubscriptionDescriptor.CommunicationParameters.UadpDataSetReaderMessageParameters.DataSetOffset = 15

            ' Instantiate the subscriber object and hook events.
            Dim subscriber = New EasyUASubscriber()
            AddHandler subscriber.DataSetMessage, AddressOf subscriber_DataSetMessage_Metadata

            Console.WriteLine("Subscribing...")
            subscriber.SubscribeDataSet(dataSetSubscriptionDescriptor)

            Console.WriteLine("Processing dataset message events for 20 seconds...")
            Threading.Thread.Sleep(20 * 1000)

            Console.WriteLine("Unsubscribing...")
            subscriber.UnsubscribeAllDataSets()

            Console.WriteLine("Waiting for 1 second...")
            ' Unsubscribe operation is asynchronous, messages may still come for a short while.
            Threading.Thread.Sleep(1 * 1000)

            Console.WriteLine("Finished...")
        End Sub

        Private Shared Sub subscriber_DataSetMessage_Metadata(ByVal sender As Object, ByVal e As EasyUADataSetMessageEventArgs)
            ' Display the dataset.
            If e.Succeeded Then
                ' An event with null DataSetData just indicates a successful connection.
                If e.DataSetData IsNot Nothing Then
                    Console.WriteLine()
                    Console.WriteLine($"Dataset data: {e.DataSetData}")
                    For Each pair As KeyValuePair(Of String, UADataSetFieldData) In e.DataSetData.FieldDataDictionary
                        Console.WriteLine(pair)
                    Next
                End If
            Else
                Console.WriteLine()
                Console.WriteLine($"*** Failure: {e.ErrorMessageBrief}")
            End If
        End Sub
    End Class

    ' Example output
    '
    'Subscribing...
    'Processing dataset message events for 20 seconds...
    '
    'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
    '[BoolToggle, False {System.Boolean}; Good]
    '[Int32, 3072 {System.Int32}; Good]
    '[Int32Fast, 894 {System.Int32}; Good]
    '[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good]
    '
    'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
    '[BoolToggle, False {System.Boolean}; Good]
    '[Int32, 3072 {System.Int32}; Good]
    '[Int32Fast, 920 {System.Int32}; Good]
    '[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good]
    '
    'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
    '[BoolToggle, False {System.Boolean}; Good]
    '[Int32, 3073 {System.Int32}; Good]
    '[Int32Fast, 1003 {System.Int32}; Good]
    '[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good]
    '
    'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
    '[BoolToggle, False {System.Boolean}; Good]
    '[Int32, 3073 {System.Int32}; Good]
    '[Int32Fast, 1074 {System.Int32}; Good]
    '[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good]
    '
    'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
    '[BoolToggle, True {System.Boolean}; Good]
    '[Int32, 3074 {System.Int32}; Good]
    '[Int32Fast, 1140 {System.Int32}; Good]
    '[DateTime, 10/1/2019 12:21:16 PM {System.DateTime}; Good]
    '
    '...

End Namespace

COM

// This example shows how to subscribe to dataset messages with RawData field encoding, specifying the metadata necessary
// for their decoding directly in the code.
//
// In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see
// https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used.
//
// Find all latest examples here : https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .

type
  TSubscriberEventHandlers78 = class
    procedure OnDataSetMessage(
      ASender: TObject;
      sender: OleVariant;
      const eventArgs: _EasyUADataSetMessageEventArgs);
  end;

class procedure SubscribeDataSet.Metadata;
var
  ConnectionDescriptor: _UAPubSubConnectionDescriptor;
  Field1, Field2, Field3, Field4: _UAFieldMetaData;
  MetaData: _UADataSetMetaData;
  SubscribeDataSetArguments: _EasyUASubscribeDataSetArguments;
  Subscriber: TEasyUASubscriber;
  SubscriberEventHandlers: TSubscriberEventHandlers78;
begin
  // Define the PubSub connection we will work with.
  SubscribeDataSetArguments := CoEasyUASubscribeDataSetArguments.Create;
  ConnectionDescriptor := SubscribeDataSetArguments.DataSetSubscriptionDescriptor.ConnectionDescriptor;
  ConnectionDescriptor.ResourceAddress.ResourceDescriptor.UrlString := 'opc.udp://239.0.0.1';
  // In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to
  // the statement below. Your actual interface name may differ, of course.
  //ConnectionDescriptor.ResourceAddress.InterfaceName := 'Ethernet';

  // Define the filter. Publisher Id (unsigned 16-bits) is 30, and the writer group Id is 101.
  // The dataset writer Id (1) must not be specified in the filter, because it does not appear in the message.
  SubscribeDataSetArguments.DataSetSubscriptionDescriptor.Filter.PublisherId.SetUint16Identifier(30);
  SubscribeDataSetArguments.DataSetSubscriptionDescriptor.Filter.WriterGroupDescriptor.WriterGroupId := 101;

  // Define the metadata. For UADP, the order of field metadata must correspond to the order of fields in the dataset message.
  MetaData := CoUADataSetMetaData.Create;
  //
  Field1 := CoUAFieldMetaData.Create;
  Field1.BuiltInType := UABuiltInType_Boolean;
  Field1.Name := 'BoolToggle';
  MetaData.Add(Field1);
  //
  Field2 := CoUAFieldMetaData.Create;
  Field2.BuiltInType := UABuiltInType_Int32;
  Field2.Name := 'Int32';
  MetaData.Add(Field2);
  //
  Field3 := CoUAFieldMetaData.Create;
  Field3.BuiltInType := UABuiltInType_Int32;
  Field3.Name := 'Int32Fast';
  MetaData.Add(Field3);
  //
  Field4 := CoUAFieldMetaData.Create;
  Field4.BuiltInType := UABuiltInType_DateTime;
  Field4.Name := 'DateTime';
  MetaData.Add(Field4);
  //
  SubscribeDataSetArguments.DataSetSubscriptionDescriptor.DataSetMetaData := MetaData;

  // Define the specific communication parameters for the dataset subscription.
  // The dataset offset is needed with messages that do not contain dataset writer Ids and use RawData field
  // encoding. An exception to this rule is when the dataset is the only or first in the dataset message payload,
  // which is also the case here, but we are specifying the dataset offset anyway, for illustration.
  SubscribeDataSetArguments.DataSetSubscriptionDescriptor.CommunicationParameters.UadpDataSetReaderMessageParameters.DataSetOffset := 15;

  // Instantiate the subscriber object and hook events.
  Subscriber := TEasyUASubscriber.Create(nil);
  SubscriberEventHandlers := TSubscriberEventHandlers78.Create;
  Subscriber.OnDataSetMessage := SubscriberEventHandlers.OnDataSetMessage;

  WriteLn('Subscribing...');
  Subscriber.SubscribeDataSet(SubscribeDataSetArguments);

  WriteLn('Processing dataset message for 20 seconds...');
  PumpSleep(20*1000);

  WriteLn('Unsubscribing...');
  Subscriber.UnsubscribeAllDataSets;

  WriteLn('Waiting for 1 second...');
  // Unsubscribe operation is asynchronous, messages may still come for a short while.
  PumpSleep(1*1000);

  WriteLn('Finished.');
  FreeAndNil(Subscriber);
  FreeAndNil(SubscriberEventHandlers);
end;

procedure TSubscriberEventHandlers78.OnDataSetMessage(
  ASender: TObject;
  sender: OleVariant;
  const eventArgs: _EasyUADataSetMessageEventArgs);
var
  Count: Cardinal;
  DictionaryEntry2: _DictionaryEntry2;
  Element: OleVariant;
  FieldDataDictionaryEnumerator: IEnumVariant;
begin
  // Display the dataset.
  if eventArgs.Succeeded then
  begin
    // An event with null DataSetData just indicates a successful connection.
    if eventArgs.DataSetData <> nil then
    begin
      WriteLn;
      WriteLn('Dataset data: ', eventArgs.DataSetData.ToString);
      FieldDataDictionaryEnumerator := eventArgs.DataSetData.FieldDataDictionary.GetEnumerator;
      while (FieldDataDictionaryEnumerator.Next(1, Element, Count) = S_OK) do
      begin
        DictionaryEntry2 := IUnknown(Element) as _DictionaryEntry2;
        WriteLn(DictionaryEntry2.ToString);
      end;
    end;
  end
  else begin
    WriteLn;
      WriteLn('*** Failure: ', eventArgs.ErrorMessageBrief);
  end;
end;

// Example output:
//
//Subscribing...
//Processing dataset message events for 20 seconds...
//
//Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
//[BoolToggle, False {System.Boolean}; Good]
//[Int32, 3072 {System.Int32}; Good]
//[Int32Fast, 894 {System.Int32}; Good]
//[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good]
//
//Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
//[BoolToggle, False {System.Boolean}; Good]
//[Int32, 3072 {System.Int32}; Good]
//[Int32Fast, 920 {System.Int32}; Good]
//[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good]
//
//Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
//[BoolToggle, False {System.Boolean}; Good]
//[Int32, 3073 {System.Int32}; Good]
//[Int32Fast, 1003 {System.Int32}; Good]
//[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good]
//
//Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
//[BoolToggle, False {System.Boolean}; Good]
//[Int32, 3073 {System.Int32}; Good]
//[Int32Fast, 1074 {System.Int32}; Good]
//[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good]
//
//Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
//[BoolToggle, True {System.Boolean}; Good]
//[Int32, 3074 {System.Int32}; Good]
//[Int32Fast, 1140 {System.Int32}; Good]
//[DateTime, 10/1/2019 12:21:16 PM {System.DateTime}; Good]
//
//...

Rem This example shows how to subscribe to dataset messages with RawData field encoding, specifying the metadata necessary
Rem for their decoding directly in the code.
Rem
Rem In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see
Rem https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used.
Rem
Rem Find all latest examples here : https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .

Option Explicit

Const UABuiltInType_Boolean = 1
Const UABuiltInType_Int32 = 6
Const UABuiltInType_DateTime = 13

' Define the PubSub connection we will work with.
Dim SubscribeDataSetArguments: Set SubscribeDataSetArguments = CreateObject("OpcLabs.EasyOpc.UA.PubSub.OperationModel.EasyUASubscribeDataSetArguments")
Dim ConnectionDescriptor: Set ConnectionDescriptor = SubscribeDataSetArguments.DataSetSubscriptionDescriptor.ConnectionDescriptor
ConnectionDescriptor.ResourceAddress.ResourceDescriptor.UrlString = "opc.udp://239.0.0.1"
' In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to
' the statement below. Your actual interface name may differ, of course.
' ConnectionDescriptor.ResourceAddress.InterfaceName = "Ethernet"

' Define the filter. Publisher Id (unsigned 16-bits) is 30, and the writer group Id is 101.
' The dataset writer Id (1) must not be specified in the filter, because it does not appear in the message.
SubscribeDataSetArguments.DataSetSubscriptionDescriptor.Filter.PublisherId.SetUInt16Identifier 30
SubscribeDataSetArguments.DataSetSubscriptionDescriptor.Filter.WriterGroupDescriptor.WriterGroupId = 101

' Define the metadata. For UADP, the order of field metadata must correspond to the order of fields in the dataset message.
Dim MetaData: Set MetaData = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UADataSetMetaData")
'
Dim Field1: Set Field1 = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UAFieldMetaData")
Field1.BuiltInType = UABuiltInType_Boolean
Field1.Name = "BoolToggle"
MetaData.Add(Field1)
'
Dim Field2: Set Field2 = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UAFieldMetaData")
Field2.BuiltInType = UABuiltInType_Int32
Field2.Name = "Int32"
MetaData.Add(Field2)
'
Dim Field3: Set Field3 = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UAFieldMetaData")
Field3.BuiltInType = UABuiltInType_Int32
Field3.Name = "Int32Fast"
MetaData.Add(Field3)
'
Dim Field4: Set Field4 = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UAFieldMetaData")
Field4.BuiltInType = UABuiltInType_DateTime
Field4.Name = "DateTime"
MetaData.Add(Field4)
'
Set SubscribeDataSetArguments.DataSetSubscriptionDescriptor.DataSetMetaData = MetaData

' Define the specific communication parameters for the dataset subscription.
' The dataset offset is needed with messages that do not contain dataset writer Ids and use RawData field
' encoding. An exception to this rule is when the dataset is the only or first in the dataset message payload,
' which is also the case here, but we are specifying the dataset offset anyway, for illustration.
SubscribeDataSetArguments.DataSetSubscriptionDescriptor.CommunicationParameters.UadpDataSetReaderMessageParameters.DataSetOffset = 15

' Instantiate the subscriber object and hook events.
Dim Subscriber: Set Subscriber = CreateObject("OpcLabs.EasyOpc.UA.PubSub.EasyUASubscriber")
WScript.ConnectObject Subscriber, "Subscriber_"

WScript.Echo "Subscribing..."
Subscriber.SubscribeDataSet SubscribeDataSetArguments

WScript.Echo "Processing dataset message events for 20 seconds..."
WScript.Sleep 20*1000

WScript.Echo "Unsubscribing..."
Subscriber.UnsubscribeAllDataSets

WScript.Echo "Waiting for 1 second..."
' Unsubscribe operation is asynchronous, messages may still come for a short while.
WScript.Sleep 1*1000

WScript.Echo "Finished."



Sub Subscriber_DataSetMessage(Sender, e)
    ' Display the dataset.
    If e.Succeeded Then
        ' An event with null DataSetData just indicates a successful connection.
        If Not (e.DataSetData Is Nothing) Then
            WScript.Echo
            WScript.Echo "Dataset data: " & e.DataSetData
            Dim Pair: For Each Pair in e.DataSetData.FieldDataDictionary
                WScript.Echo Pair
            Next
        End If
    Else
        WScript.Echo
        WScript.Echo "*** Failure: " & e.ErrorMessageBrief
    End If
End Sub



' Example output:
'
'Subscribing...
'Processing dataset message events for 20 seconds...
'
'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
'[BoolToggle, False {System.Boolean}; Good]
'[Int32, 3072 {System.Int32}; Good]
'[Int32Fast, 894 {System.Int32}; Good]
'[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good]
'
'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
'[BoolToggle, False {System.Boolean}; Good]
'[Int32, 3072 {System.Int32}; Good]
'[Int32Fast, 920 {System.Int32}; Good]
'[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good]
'
'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
'[BoolToggle, False {System.Boolean}; Good]
'[Int32, 3073 {System.Int32}; Good]
'[Int32Fast, 1003 {System.Int32}; Good]
'[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good]
'
'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
'[BoolToggle, False {System.Boolean}; Good]
'[Int32, 3073 {System.Int32}; Good]
'[Int32Fast, 1074 {System.Int32}; Good]
'[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good]
'
'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
'[BoolToggle, True {System.Boolean}; Good]
'[Int32, 3074 {System.Int32}; Good]
'[Int32Fast, 1140 {System.Int32}; Good]
'[DateTime, 10/1/2019 12:21:16 PM {System.DateTime}; Good]
'
'...

REM This example shows how to subscribe to dataset messages with RawData field encoding, specifying the metadata necessary
REM for their decoding directly in the code.
REM
REM In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see
REM https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used.
REM
REM Find all latest examples here : https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .

' The subscriber object, with events
'Public WithEvents Subscriber3 As EasyUASubscriber

Private Sub EasyUASubscriber_SubscribeDataSet_Metadata_Command_Click()
    OutputText = ""

    ' Define the PubSub connection we will work with.
    Dim subscribeDataSetArguments As New EasyUASubscribeDataSetArguments
    Dim ConnectionDescriptor As UAPubSubConnectionDescriptor
    Set ConnectionDescriptor = subscribeDataSetArguments.dataSetSubscriptionDescriptor.ConnectionDescriptor
    ConnectionDescriptor.ResourceAddress.ResourceDescriptor.UrlString = "opc.udp://239.0.0.1"
    ' In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to
    ' the statement below. Your actual interface name may differ, of course.
    'ConnectionDescriptor.ResourceAddress.InterfaceName := 'Ethernet';

    ' Define the filter. Publisher Id (unsigned 16-bits) is 30, and the writer group Id is 101.
    ' The dataset writer Id (1) must not be specified in the filter, because it does not appear in the message.
    Call subscribeDataSetArguments.dataSetSubscriptionDescriptor.Filter.PublisherId.SetUInt16Identifier(30)
    subscribeDataSetArguments.dataSetSubscriptionDescriptor.Filter.WriterGroupDescriptor.WriterGroupId = 101

    ' Define the metadata. For UADP, the order of field metadata must correspond to the order of fields in the dataset message.
    Dim metaData As New UADataSetMetaData
    '
    Dim field1 As New UAFieldMetaData
    field1.BuiltInType = UABuiltInType_Boolean
    field1.Name = "BoolToggle"
    metaData.Add field1
    '
    Dim field2 As New UAFieldMetaData
    field2.BuiltInType = UABuiltInType_Int32
    field2.Name = "Int32"
    metaData.Add field2
    '
    Dim field3 As New UAFieldMetaData
    field3.BuiltInType = UABuiltInType_Int32
    field3.Name = "Int32Fast"
    metaData.Add field3
    '
    Dim field4 As New UAFieldMetaData
    field4.BuiltInType = UABuiltInType_DateTime
    field4.Name = "DateTime"
    metaData.Add field4
    '
    Set subscribeDataSetArguments.dataSetSubscriptionDescriptor.DataSetMetaData = metaData
    
    ' Define the specific communication parameters for the dataset subscription.
    ' The dataset offset is needed with messages that do not contain dataset writer Ids and use RawData field
    ' encoding. An exception to this rule is when the dataset is the only or first in the dataset message payload,
    ' which is also the case here, but we are specifying the dataset offset anyway, for illustration.
    subscribeDataSetArguments.dataSetSubscriptionDescriptor.CommunicationParameters.UadpDataSetReaderMessageParameters.DataSetOffset = 15
    
    ' Instantiate the subscriber object and hook events.
    Set Subscriber3 = New EasyUASubscriber
    
    OutputText = OutputText & "Subscribing..." & vbCrLf
    Call Subscriber3.SubscribeDataSet(subscribeDataSetArguments)

    OutputText = OutputText & "Processing dataset message for 20 seconds..." & vbCrLf
    Pause 20000

    OutputText = OutputText & "Unsubscribing..." & vbCrLf
    Subscriber3.UnsubscribeAllDataSets

    OutputText = OutputText & "Waiting for 1 second..." & vbCrLf
    ' Unsubscribe operation is asynchronous, messages may still come for a short while.
    Pause 1000

    Set Subscriber3 = Nothing

    OutputText = OutputText & "Finished." & vbCrLf
End Sub

Private Sub Subscriber3_DataSetMessage(ByVal sender As Variant, ByVal eventArgs As EasyUADataSetMessageEventArgs)
    ' Display the dataset
    If eventArgs.Succeeded Then
        ' An event with null DataSetData just indicates a successful connection.
        If Not eventArgs.DataSetData Is Nothing Then
            OutputText = OutputText & vbCrLf
            OutputText = OutputText & "Dataset data: " & eventArgs.DataSetData & vbCrLf
            Dim dictionaryEntry2 : For Each dictionaryEntry2 In eventArgs.DataSetData.FieldDataDictionary
                OutputText = OutputText & dictionaryEntry2 & vbCrLf
            Next
        End If
    Else
        OutputText = OutputText & vbCrLf
        OutputText = OutputText & "*** Failure: " & eventArgs.ErrorMessageBrief & vbCrLf
    End If
End Sub
' Example output:
'
'Subscribing...
'Processing dataset message events for 20 seconds...
'
'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
'[BoolToggle, False {System.Boolean}; Good]
'[Int32, 3072 {System.Int32}; Good]
'[Int32Fast, 894 {System.Int32}; Good]
'[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good]
'
'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
'[BoolToggle, False {System.Boolean}; Good]
'[Int32, 3072 {System.Int32}; Good]
'[Int32Fast, 920 {System.Int32}; Good]
'[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good]
'
'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
'[BoolToggle, False {System.Boolean}; Good]
'[Int32, 3073 {System.Int32}; Good]
'[Int32Fast, 1003 {System.Int32}; Good]
'[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good]
'
'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
'[BoolToggle, False {System.Boolean}; Good]
'[Int32, 3073 {System.Int32}; Good]
'[Int32Fast, 1074 {System.Int32}; Good]
'[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good]
'
'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4
'[BoolToggle, True {System.Boolean}; Good]
'[Int32, 3074 {System.Int32}; Good]
'[Int32Fast, 1140 {System.Int32}; Good]
'[DateTime, 10/1/2019 12:21:16 PM {System.DateTime}; Good]
'
'...

Partial metadata

In some cases, partial metadata is sufficient to achieve the purpose. For example, your intent might be to identify dataset fields by their names, but the communication uses UADP mapping, which does not transfer the field names in the messages, and therefore some metadata is required for that. The full metadata, which includes types information for individual fields, is however only needed if RawData encoding is used. If the encoding is Variant or DataValue, type information is not strictly necessary, because dataset data can be decoded based simply on the contents of the dataset message.

You can simplify your code by only specifying field names in the metadata in such cases. This is illustrated in the example below.

.NET

// This example shows how to subscribe to dataset messages and specify field names, without having the full metadata.
//
// In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see
// https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .

using System;
using System.Collections.Generic;
using System.Threading;
using OpcLabs.EasyOpc.UA.PubSub;
using OpcLabs.EasyOpc.UA.PubSub.Configuration;
using OpcLabs.EasyOpc.UA.PubSub.OperationModel;

namespace UADocExamples.PubSub._EasyUASubscriber
{
    partial class SubscribeDataSet
    {
        public static void FieldNames()
        {
            // Define the PubSub connection we will work with. Uses implicit conversion from a string.
            UAPubSubConnectionDescriptor pubSubConnectionDescriptor = "opc.udp://239.0.0.1";
            // In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to
            // the statement below. Your actual interface name may differ, of course.
            //pubSubConnectionDescriptor.ResourceAddress.InterfaceName = "Ethernet";

            // Define the filter. Publisher Id (unsigned 64-bits) is 31, and the dataset writer Id is 1.
            var filter = new UASubscribeDataSetFilter(UAPublisherId.CreateUInt64(31), UAWriterGroupDescriptor.Null, 1);

            // Define the metadata, with the use of collection initializer for its fields. For UADP, the order of field
            // metadata must correspond to the order of fields in the dataset message.
            // Since the encoding is not RawData, we do not have to specify the type information for the fields.
            var metaData = new UADataSetMetaData
            {
                new UAFieldMetaData("BoolToggle"),
                new UAFieldMetaData("Int32"),
                new UAFieldMetaData("Int32Fast"),
                new UAFieldMetaData("DateTime")
            };

            // Instantiate the subscriber object and hook events.
            var subscriber = new EasyUASubscriber();
            subscriber.DataSetMessage += subscriber_DataSetMessage_FieldNames;

            Console.WriteLine("Subscribing...");
            subscriber.SubscribeDataSet(pubSubConnectionDescriptor, filter, metaData);

            Console.WriteLine("Processing dataset message events for 20 seconds...");
            Thread.Sleep(20 * 1000);

            Console.WriteLine("Unsubscribing...");
            subscriber.UnsubscribeAllDataSets();

            Console.WriteLine("Waiting for 1 second...");
            // Unsubscribe operation is asynchronous, messages may still come for a short while.
            Thread.Sleep(1 * 1000);

            Console.WriteLine("Finished.");
        }

        static void subscriber_DataSetMessage_FieldNames(object sender, EasyUADataSetMessageEventArgs e)
        {
            // Display the dataset.
            if (e.Succeeded)
            {
                // An event with null DataSetData just indicates a successful connection.
                if (!(e.DataSetData is null))
                {
                    Console.WriteLine();
                    Console.WriteLine($"Dataset data: {e.DataSetData}");
                    foreach (KeyValuePair<string, UADataSetFieldData> pair in e.DataSetData.FieldDataDictionary)
                        Console.WriteLine(pair);
                }
            }
            else
            {
                Console.WriteLine();
                Console.WriteLine($"*** Failure: {e.ErrorMessageBrief}");
            }
        }

        // Example output:
        //
        //Subscribing...
        //Processing dataset message events for 20 seconds...
        //
        //Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
        //[BoolToggle, True {System.Boolean}; Good]
        //[Int32, 25 {System.Int32}; Good]
        //[Int32Fast, 928 {System.Int32}; Good]
        //[DateTime, 10/3/2019 10:43:01 AM {System.DateTime}; Good]
        //
        //Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
        //[Int32, 26 {System.Int32}; Good]
        //[Int32Fast, 1007 {System.Int32}; Good]
        //[DateTime, 10/3/2019 10:43:02 AM {System.DateTime}; Good]
        //[BoolToggle, True {System.Boolean}; Good]
        //
        //Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
        //[Int32Fast, 1113 {System.Int32}; Good]
        //[DateTime, 10/3/2019 10:43:02 AM {System.DateTime}; Good]
        //[BoolToggle, True {System.Boolean}; Good]
        //[Int32, 26 {System.Int32}; Good]
        //
        //Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
        //[BoolToggle, False {System.Boolean}; Good]
        //[Int32, 27 {System.Int32}; Good]
        //[Int32Fast, 1201 {System.Int32}; Good]
        //[DateTime, 10/3/2019 10:43:03 AM {System.DateTime}; Good]
        //
        //Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
        //[Int32Fast, 1260 {System.Int32}; Good]
        //[DateTime, 10/3/2019 10:43:03 AM {System.DateTime}; Good]
        //[BoolToggle, False {System.Boolean}; Good]
        //[Int32, 27 {System.Int32}; Good]
        //
        //...
    }
}

# This example shows how to subscribe to dataset messages and specify field names, without having the full metadata.
#
# In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see
# https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used.
#
# Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
# OPC client and subscriber examples in Python on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-Python .
# The QuickOPC package is needed. Install it using "pip install opclabs_quickopc".
import opclabs_quickopc
import time

# Import .NET namespaces.
from System import *
from OpcLabs.EasyOpc.UA.PubSub import *
from OpcLabs.EasyOpc.UA.PubSub.Configuration import *
from OpcLabs.EasyOpc.UA.PubSub.OperationModel import *


def dataSetMessage(sender, e):
    # Display the dataset.
    if e.Succeeded:
        # An event with null DataSetData just indicates a successful connection.
        if e.DataSetData is not None:
            print('')
            print('Dataset data: ', e.DataSetData, sep='')
            for pair in e.DataSetData.FieldDataDictionary:
                print(pair)
    else:
        print('')
        print('*** Failure: ', e.ErrorMessageBrief, sep='')


# Define the PubSub connection we will work with. Uses implicit conversion from a string.
pubSubConnectionDescriptor = UAPubSubConnectionDescriptor.op_Implicit('opc.udp://239.0.0.1')
# In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to
# the statement below. Your actual interface name may differ, of course.
#pubSubConnectionDescriptor.ResourceAddress.InterfaceName = 'Ethernet'

# Define the filter. Publisher Id (unsigned 64-bits) is 31, and the dataset writer Id is 1.
filter = UASubscribeDataSetFilter(UAPublisherId.CreateUInt64(Decimal(31)),
                                  UAWriterGroupDescriptor.Null,
                                  UADataSetWriterDescriptor(1))

# Define the metadata. For UADP, the order of field metadata must correspond to the order of fields in the dataset
# message.
# Since the encoding is not RawData, we do not have to specify the type information for the fields.
metaData = UADataSetMetaData()
metaData.Add(UAFieldMetaData('BoolToggle'))
metaData.Add(UAFieldMetaData('Int32'))
metaData.Add(UAFieldMetaData('Int32Fast'))
metaData.Add(UAFieldMetaData('DateTime'))

# Instantiate the subscriber object and hook events.
subscriber = EasyUASubscriber()
subscriber.DataSetMessage += dataSetMessage

print('Subscribing...')
IEasyUASubscriberExtension.SubscribeDataSet(subscriber, pubSubConnectionDescriptor, filter, metaData)

print('Processing dataset message events for 20 seconds...')
time.sleep(20)

print('Unsubscribing...')
subscriber.UnsubscribeAllDataSets()

print('Waiting for 1 second...')
# Unsubscribe operation is asynchronous, messages may still come for a short while.
time.sleep(1)

subscriber.DataSetMessage -= dataSetMessage

print('Finished.')

' This example shows how to subscribe to dataset messages and specify field names, without having the full metadata.
'
' In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see
' https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .

Imports OpcLabs.EasyOpc.UA.PubSub
Imports OpcLabs.EasyOpc.UA.PubSub.Configuration
Imports OpcLabs.EasyOpc.UA.PubSub.OperationModel

Namespace PubSub._EasyUASubscriber
    Partial Friend Class SubscribeDataSet
        Public Shared Sub FieldNames()

            ' Define the PubSub connection we will work with. Uses implicit conversion from a string.
            Dim pubSubConnectionDescriptor As UAPubSubConnectionDescriptor = "opc.udp://239.0.0.1"
            ' In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to
            ' the statement below. Your actual interface name may differ, of course.
            ' pubSubConnectionDescriptor.ResourceAddress.InterfaceName = "Ethernet"

            ' Define the filter. Publisher Id (unsigned 64-bits) is 31, and the dataset writer Id is 1.
            Dim filter = New UASubscribeDataSetFilter(UAPublisherId.CreateUInt64(31), UAWriterGroupDescriptor.Null, 1)

            ' Define the metadata, with the use of collection initializer for its fields. For UADP, the order of field
            ' metadata must correspond to the order of fields in the dataset message.
            ' Since the encoding is not RawData, we do not have to specify the type information for the fields.
            Dim metaData = New UADataSetMetaData From {
                New UAFieldMetaData("BoolToggle"),
                New UAFieldMetaData("Int32"),
                New UAFieldMetaData("Int32Fast"),
                New UAFieldMetaData("DateTime")
            }

            ' Instantiate the subscriber object and hook events.
            Dim subscriber = New EasyUASubscriber()
            AddHandler subscriber.DataSetMessage, AddressOf subscriber_DataSetMessage_FieldNames

            Console.WriteLine("Subscribing...")
            subscriber.SubscribeDataSet(pubSubConnectionDescriptor, filter, metaData)

            Console.WriteLine("Processing dataset message events for 20 seconds...")
            Threading.Thread.Sleep(20 * 1000)

            Console.WriteLine("Unsubscribing...")
            subscriber.UnsubscribeAllDataSets()

            Console.WriteLine("Waiting for 1 second...")
            ' Unsubscribe operation is asynchronous, messages may still come for a short while.
            Threading.Thread.Sleep(1 * 1000)

            Console.WriteLine("Finished...")
        End Sub

        Private Shared Sub subscriber_DataSetMessage_FieldNames(ByVal sender As Object, ByVal e As EasyUADataSetMessageEventArgs)
            ' Display the dataset.
            If e.Succeeded Then
                ' An event with null DataSetData just indicates a successful connection.
                If e.DataSetData IsNot Nothing Then
                    Console.WriteLine()
                    Console.WriteLine($"Dataset data: {e.DataSetData}")
                    For Each pair As KeyValuePair(Of String, UADataSetFieldData) In e.DataSetData.FieldDataDictionary
                        Console.WriteLine(pair)
                    Next
                End If
            Else
                Console.WriteLine()
                Console.WriteLine($"*** Failure: {e.ErrorMessageBrief}")
            End If
        End Sub
    End Class

    ' Example output
    '
    'Subscribing...
    'Processing dataset message events for 20 seconds...
    '
    'Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
    '[BoolToggle, True {System.Boolean}; Good]
    '[Int32, 25 {System.Int32}; Good]
    '[Int32Fast, 928 {System.Int32}; Good]
    '[DateTime, 10/3/2019 10:43:01 AM {System.DateTime}; Good]
    '
    'Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
    '[Int32, 26 {System.Int32}; Good]
    '[Int32Fast, 1007 {System.Int32}; Good]
    '[DateTime, 10/3/2019 10:43:02 AM {System.DateTime}; Good]
    '[BoolToggle, True {System.Boolean}; Good]
    '
    'Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
    '[Int32Fast, 1113 {System.Int32}; Good]
    '[DateTime, 10/3/2019 10:43:02 AM {System.DateTime}; Good]
    '[BoolToggle, True {System.Boolean}; Good]
    '[Int32, 26 {System.Int32}; Good]
    '
    'Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
    '[BoolToggle, False {System.Boolean}; Good]
    '[Int32, 27 {System.Int32}; Good]
    '[Int32Fast, 1201 {System.Int32}; Good]
    '[DateTime, 10/3/2019 10:43:03 AM {System.DateTime}; Good]
    '
    'Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
    '[Int32Fast, 1260 {System.Int32}; Good]
    '[DateTime, 10/3/2019 10:43:03 AM {System.DateTime}; Good]
    '[BoolToggle, False {System.Boolean}; Good]
    '[Int32, 27 {System.Int32}; Good]
    '
    '...

End Namespace

COM

// This example shows how to subscribe to dataset messages and specify field names, without having the full metadata.
//
// In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see
// https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used.
//
// Find all latest examples here : https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .

type
  TSubscriberEventHandlers75 = class
    procedure OnDataSetMessage(
      ASender: TObject;
      sender: OleVariant;
      const eventArgs: _EasyUADataSetMessageEventArgs);
  end;

class procedure SubscribeDataSet.FieldNames;
var
  ConnectionDescriptor: _UAPubSubConnectionDescriptor;
  Field1, Field2, Field3, Field4: _UAFieldMetaData;
  MetaData: _UADataSetMetaData;
  SubscribeDataSetArguments: _EasyUASubscribeDataSetArguments;
  Subscriber: TEasyUASubscriber;
  SubscriberEventHandlers: TSubscriberEventHandlers75;
begin
  // Define the PubSub connection we will work with.
  SubscribeDataSetArguments := CoEasyUASubscribeDataSetArguments.Create;
  ConnectionDescriptor := SubscribeDataSetArguments.DataSetSubscriptionDescriptor.ConnectionDescriptor;
  ConnectionDescriptor.ResourceAddress.ResourceDescriptor.UrlString := 'opc.udp://239.0.0.1';
  // In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to
  // the statement below. Your actual interface name may differ, of course.
  //ConnectionDescriptor.ResourceAddress.InterfaceName := 'Ethernet';

  // Define the filter. Publisher Id (unsigned 64-bits) is 31, and the dataset writer Id is 1.
  SubscribeDataSetArguments.DataSetSubscriptionDescriptor.Filter.PublisherId.SetIdentifier(UAPublisherIdType_UInt64, 31);
  SubscribeDataSetArguments.DataSetSubscriptionDescriptor.Filter.DataSetWriterDescriptor.DataSetWriterId := 1;

  // Define the metadata, with the use of collection initializer for its fields. For UADP, the order of field
  // metadata must correspond to the order of fields in the dataset message.
  // Since the encoding is not RawData, we do not have to specify the type information for the fields.
  MetaData := CoUADataSetMetaData.Create;
  //
  Field1 := CoUAFieldMetaData.Create;
  Field1.Name := 'BoolToggle';
  MetaData.Add(Field1);
  //
  Field2 := CoUAFieldMetaData.Create;
  Field2.Name := 'Int32';
  MetaData.Add(Field2);
  //
  Field3 := CoUAFieldMetaData.Create;
  Field3.Name := 'Int32Fast';
  MetaData.Add(Field3);
  //
  Field4 := CoUAFieldMetaData.Create;
  Field4.Name := 'DateTime';
  MetaData.Add(Field4);
  //
  SubscribeDataSetArguments.DataSetSubscriptionDescriptor.DataSetMetaData := MetaData;

  // Instantiate the subscriber object and hook events.
  Subscriber := TEasyUASubscriber.Create(nil);
  SubscriberEventHandlers := TSubscriberEventHandlers75.Create;
  Subscriber.OnDataSetMessage := SubscriberEventHandlers.OnDataSetMessage;

  WriteLn('Subscribing...');
  Subscriber.SubscribeDataSet(SubscribeDataSetArguments);

  WriteLn('Processing dataset message for 20 seconds...');
  PumpSleep(20*1000);

  WriteLn('Unsubscribing...');
  Subscriber.UnsubscribeAllDataSets;

  WriteLn('Waiting for 1 second...');
  // Unsubscribe operation is asynchronous, messages may still come for a short while.
  PumpSleep(1*1000);

  WriteLn('Finished.');
  FreeAndNil(Subscriber);
  FreeAndNil(SubscriberEventHandlers);
end;

procedure TSubscriberEventHandlers75.OnDataSetMessage(
  ASender: TObject;
  sender: OleVariant;
  const eventArgs: _EasyUADataSetMessageEventArgs);
var
  Count: Cardinal;
  DictionaryEntry2: _DictionaryEntry2;
  Element: OleVariant;
  FieldDataDictionaryEnumerator: IEnumVariant;
begin
  // Display the dataset.
  if eventArgs.Succeeded then
  begin
    // An event with null DataSetData just indicates a successful connection.
    if eventArgs.DataSetData <> nil then
    begin
      WriteLn;
      WriteLn('Dataset data: ', eventArgs.DataSetData.ToString);
      FieldDataDictionaryEnumerator := eventArgs.DataSetData.FieldDataDictionary.GetEnumerator;
      while (FieldDataDictionaryEnumerator.Next(1, Element, Count) = S_OK) do
      begin
        DictionaryEntry2 := IUnknown(Element) as _DictionaryEntry2;
        WriteLn(DictionaryEntry2.ToString);
      end;
    end;
  end
  else begin
    WriteLn;
      WriteLn('*** Failure: ', eventArgs.ErrorMessageBrief);
  end;
end;

// Example output:
//
//Subscribing...
//Processing dataset message events for 20 seconds...
//
//Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
//[BoolToggle, True {System.Boolean}; Good]
//[Int32, 25 {System.Int32}; Good]
//[Int32Fast, 928 {System.Int32}; Good]
//[DateTime, 10/3/2019 10:43:01 AM {System.DateTime}; Good]
//
//Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
//[Int32, 26 {System.Int32}; Good]
//[Int32Fast, 1007 {System.Int32}; Good]
//[DateTime, 10/3/2019 10:43:02 AM {System.DateTime}; Good]
//[BoolToggle, True {System.Boolean}; Good]
//
//Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
//[Int32Fast, 1113 {System.Int32}; Good]
//[DateTime, 10/3/2019 10:43:02 AM {System.DateTime}; Good]
//[BoolToggle, True {System.Boolean}; Good]
//[Int32, 26 {System.Int32}; Good]
//
//Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
//[BoolToggle, False {System.Boolean}; Good]
//[Int32, 27 {System.Int32}; Good]
//[Int32Fast, 1201 {System.Int32}; Good]
//[DateTime, 10/3/2019 10:43:03 AM {System.DateTime}; Good]
//
//Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
//[Int32Fast, 1260 {System.Int32}; Good]
//[DateTime, 10/3/2019 10:43:03 AM {System.DateTime}; Good]
//[BoolToggle, False {System.Boolean}; Good]
//[Int32, 27 {System.Int32}; Good]
//
//...

Rem This example shows how to subscribe to dataset messages and specify field names, without having the full metadata.
Rem
Rem In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see
Rem https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used.
Rem
Rem Find all latest examples here : https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .

Option Explicit

Const UAPublisherIdType_UInt64 = 4

' Define the PubSub connection we will work with.
Dim SubscribeDataSetArguments: Set SubscribeDataSetArguments = CreateObject("OpcLabs.EasyOpc.UA.PubSub.OperationModel.EasyUASubscribeDataSetArguments")
Dim ConnectionDescriptor: Set ConnectionDescriptor = SubscribeDataSetArguments.DataSetSubscriptionDescriptor.ConnectionDescriptor
ConnectionDescriptor.ResourceAddress.ResourceDescriptor.UrlString = "opc.udp://239.0.0.1"
' In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to
' the statement below. Your actual interface name may differ, of course.
' ConnectionDescriptor.ResourceAddress.InterfaceName = "Ethernet"

' Define the filter. Publisher Id (unsigned 64-bits) is 31, and the dataset writer Id is 1.
SubscribeDataSetArguments.DataSetSubscriptionDescriptor.Filter.PublisherId.SetIdentifier UAPublisherIdType_UInt64, 31
SubscribeDataSetArguments.DataSetSubscriptionDescriptor.Filter.DataSetWriterDescriptor.DataSetWriterId = 1

' Define the metadata. For UADP, the order of field metadata must correspond to the order of fields in the dataset message.
' Since the encoding is not RawData, we do not have to specify the type information for the fields.
Dim MetaData: Set MetaData = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UADataSetMetaData")
'
Dim Field1: Set Field1 = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UAFieldMetaData")
Field1.Name = "BoolToggle"
MetaData.Add(Field1)
'
Dim Field2: Set Field2 = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UAFieldMetaData")
Field2.Name = "Int32"
MetaData.Add(Field2)
'
Dim Field3: Set Field3 = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UAFieldMetaData")
Field3.Name = "Int32Fast"
MetaData.Add(Field3)
'
Dim Field4: Set Field4 = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UAFieldMetaData")
Field4.Name = "DateTime"
MetaData.Add(Field4)
'
Set SubscribeDataSetArguments.DataSetSubscriptionDescriptor.DataSetMetaData = MetaData

' Instantiate the subscriber object and hook events.
Dim Subscriber: Set Subscriber = CreateObject("OpcLabs.EasyOpc.UA.PubSub.EasyUASubscriber")
WScript.ConnectObject Subscriber, "Subscriber_"

WScript.Echo "Subscribing..."
Subscriber.SubscribeDataSet SubscribeDataSetArguments

WScript.Echo "Processing dataset message events for 20 seconds..."
WScript.Sleep 20*1000

WScript.Echo "Unsubscribing..."
Subscriber.UnsubscribeAllDataSets

WScript.Echo "Waiting for 1 second..."
' Unsubscribe operation is asynchronous, messages may still come for a short while.
WScript.Sleep 1*1000



Sub Subscriber_DataSetMessage(Sender, e)
    ' Display the dataset.
    If e.Succeeded Then
        ' An event with null DataSetData just indicates a successful connection.
        If Not (e.DataSetData Is Nothing) Then
            WScript.Echo
            WScript.Echo "Dataset data: " & e.DataSetData
            Dim Pair: For Each Pair in e.DataSetData.FieldDataDictionary
                WScript.Echo Pair
            Next
        End If
    Else
        WScript.Echo
        WScript.Echo "*** Failure: " & e.ErrorMessageBrief
    End If
End Sub

WScript.Echo "Finished."



' Example output:
'
'Subscribing...
'Processing dataset message events for 20 seconds...
'
'Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
'[BoolToggle, True {System.Boolean}; Good]
'[Int32, 25 {System.Int32}; Good]
'[Int32Fast, 928 {System.Int32}; Good]
'[DateTime, 10/3/2019 10:43:01 AM {System.DateTime}; Good]
'
'Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
'[Int32, 26 {System.Int32}; Good]
'[Int32Fast, 1007 {System.Int32}; Good]
'[DateTime, 10/3/2019 10:43:02 AM {System.DateTime}; Good]
'[BoolToggle, True {System.Boolean}; Good]
'
'Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
'[Int32Fast, 1113 {System.Int32}; Good]
'[DateTime, 10/3/2019 10:43:02 AM {System.DateTime}; Good]
'[BoolToggle, True {System.Boolean}; Good]
'[Int32, 26 {System.Int32}; Good]
'
'Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
'[BoolToggle, False {System.Boolean}; Good]
'[Int32, 27 {System.Int32}; Good]
'[Int32Fast, 1201 {System.Int32}; Good]
'[DateTime, 10/3/2019 10:43:03 AM {System.DateTime}; Good]
'
'Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
'[Int32Fast, 1260 {System.Int32}; Good]
'[DateTime, 10/3/2019 10:43:03 AM {System.DateTime}; Good]
'[BoolToggle, False {System.Boolean}; Good]
'[Int32, 27 {System.Int32}; Good]
'
'...

REM This example shows how to subscribe to dataset messages and specify field names, without having the full metadata.
REM
REM In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see
REM https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used.
REM
REM Find all latest examples here : https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .

' The subscriber object, with events.
'Public WithEvents Subscriber8 As EasyUASubscriber

Private Sub EasyUASubscriber_SubscribeDataSet_FieldNames_Command_Click()
    OutputText = ""

    ' Define the PubSub connection we will work with.
    Dim subscribeDataSetArguments :  Set subscribeDataSetArguments = CreateObject("OpcLabs.EasyOpc.UA.PubSub.OperationModel.EasyUASubscribeDataSetArguments")
    Dim ConnectionDescriptor :  Set ConnectionDescriptor = subscribeDataSetArguments.dataSetSubscriptionDescriptor.ConnectionDescriptor
    ConnectionDescriptor.ResourceAddress.ResourceDescriptor.UrlString = "opc.udp://239.0.0.1"
    ' In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to
    ' the statement below. Your actual interface name may differ, of course.
    ' ConnectionDescriptor.ResourceAddress.InterfaceName = "Ethernet"

    ' Define the filter. Publisher Id (unsigned 64-bits) is 31, and the dataset writer Id is 1.
    subscribeDataSetArguments.dataSetSubscriptionDescriptor.Filter.PublisherId.SetIdentifier UAPublisherIdType_UInt64, 31
    subscribeDataSetArguments.dataSetSubscriptionDescriptor.Filter.DataSetWriterDescriptor.DataSetWriterId = 1

    ' Define the metadata. For UADP, the order of field metadata must correspond to the order of fields in the dataset message.
    ' Since the encoding is not RawData, we do not have to specify the type information for the fields.
    Dim metaData :  Set metaData = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UADataSetMetaData")
    '
    Dim field1 :  Set field1 = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UAFieldMetaData")
    field1.Name = "BoolToggle"
    metaData.Add(field1)
    '
    Dim field2 :  Set field2 = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UAFieldMetaData")
    field2.Name = "Int32"
    metaData.Add(field2)
    '
    Dim field3 :  Set field3 = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UAFieldMetaData")
    field3.Name = "Int32Fast"
    metaData.Add(field3)
    '
    Dim field4 :  Set field4 = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UAFieldMetaData")
    field4.Name = "DateTime"
    metaData.Add(field4)
    '
    Set subscribeDataSetArguments.dataSetSubscriptionDescriptor.DataSetMetaData = metaData

    ' Instantiate the subscriber object and hook events.
    Set Subscriber8 = New EasyUASubscriber

    OutputText = OutputText & "Subscribing..." & vbCrLf
    Subscriber8.SubscribeDataSet subscribeDataSetArguments

    OutputText = OutputText & "Processing dataset message events for 20 seconds..." & vbCrLf
    Pause 20 * 1000

    OutputText = OutputText & "Unsubscribing..." & vbCrLf
    Subscriber8.UnsubscribeAllDataSets

    OutputText = OutputText & "Waiting for 1 second..." & vbCrLf
    ' Unsubscribe operation is asynchronous, messages may still come for a short while.
    Pause 1000

    Set Subscriber8 = Nothing

    OutputText = OutputText & "Finished." & vbCrLf
End Sub

Private Sub Subscriber8_DataSetMessage(ByVal sender As Variant, ByVal eventArgs As EasyUADataSetMessageEventArgs)
    ' Display the dataset.
    If eventArgs.Succeeded Then
        ' An event with null DataSetData just indicates a successful connection.
        If Not (eventArgs.DataSetData Is Nothing) Then
            OutputText = OutputText & vbCrLf
            OutputText = OutputText & "Dataset data: " & eventArgs.DataSetData & vbCrLf
            Dim Pair : For Each Pair In eventArgs.DataSetData.FieldDataDictionary
                OutputText = OutputText & Pair & vbCrLf
            Next
        End If
    Else
        OutputText = OutputText & vbCrLf
        OutputText = OutputText & "*** Failure: " & eventArgs.ErrorMessageBrief & vbCrLf
    End If
End Sub
'
' Example output:
'
'Subscribing...
'Processing dataset message events for 20 seconds...
'
'Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
'[BoolToggle, True {System.Boolean}; Good]
'[Int32, 25 {System.Int32}; Good]
'[Int32Fast, 928 {System.Int32}; Good]
'[DateTime, 10/3/2019 10:43:01 AM {System.DateTime}; Good]
'
'Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
'[Int32, 26 {System.Int32}; Good]
'[Int32Fast, 1007 {System.Int32}; Good]
'[DateTime, 10/3/2019 10:43:02 AM {System.DateTime}; Good]
'[BoolToggle, True {System.Boolean}; Good]
'
'Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
'[Int32Fast, 1113 {System.Int32}; Good]
'[DateTime, 10/3/2019 10:43:02 AM {System.DateTime}; Good]
'[BoolToggle, True {System.Boolean}; Good]
'[Int32, 26 {System.Int32}; Good]
'
'Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
'[BoolToggle, False {System.Boolean}; Good]
'[Int32, 27 {System.Int32}; Good]
'[Int32Fast, 1201 {System.Int32}; Good]
'[DateTime, 10/3/2019 10:43:03 AM {System.DateTime}; Good]
'
'Dataset data: Good; Data; publisher=(UInt64)31, writer=1, fields: 4
'[Int32Fast, 1260 {System.Int32}; Good]
'[DateTime, 10/3/2019 10:43:03 AM {System.DateTime}; Good]
'[BoolToggle, False {System.Boolean}; Good]
'[Int32, 27 {System.Int32}; Good]
'
'...
'

Examples - OPC UA PubSub

Examples - OPC UA PubSub - Specify field names for UADP message

Examples - OPC UA PubSub - Ethernet UADP mapping

Examples - OPC UA PubSub - Resolve parameters given published dataset name

Examples - OPC UA PubSub - Specify metadata for RawData encoding

Reference

UADataSetMetaData Class

UAFieldMetaDataCollection Class

UAFieldMetaData Class

UADataSetSubscriptionDescriptor Class